<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  
  <title>SDWBA.jl</title>
  

  <link rel="shortcut icon" href="./img/favicon.ico">

  
  <link href='https://fonts.googleapis.com/css?family=Lato:400,700|Roboto+Slab:400,700|Inconsolata:400,700' rel='stylesheet' type='text/css'>

  <link rel="stylesheet" href="./css/theme.css" type="text/css" />
  <link rel="stylesheet" href="./css/theme_extra.css" type="text/css" />
  <link rel="stylesheet" href="./css/highlight.css">

  
  <script>
    // Current page data
    var mkdocs_page_name = "None";
  </script>
  
  <script src="./js/jquery-2.1.1.min.js"></script>
  <script src="./js/modernizr-2.8.3.min.js"></script>
  <script type="text/javascript" src="./js/highlight.pack.js"></script>
  <script src="./js/theme.js"></script> 

  
</head>

<body class="wy-body-for-nav" role="document">

  <div class="wy-grid-for-nav">

    
    <nav data-toggle="wy-nav-shift" class="wy-nav-side stickynav">
      <div class="wy-side-nav-search">
        <a href="." class="icon icon-home"> SDWBA.jl</a>
        <div role="search">
  <form id ="rtd-search-form" class="wy-form" action="./search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" />
  </form>
</div>
      </div>

      <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
        <ul class="current">
          
            <li>
    <li class="toctree-l1 current">
        <a class="current" href=".">Introduction</a>
        
            <ul>
            
                <li class="toctree-l3"><a href="#sdwba">SDWBA</a></li>
                
                    <li><a class="toctree-l4" href="#installation">Installation</a></li>
                
                    <li><a class="toctree-l4" href="#basic-use">Basic use</a></li>
                
            
            </ul>
        
    </li>
<li>
          
            <li>
    <li class="toctree-l1 ">
        <a class="" href="API/">Function Reference</a>
        
    </li>
<li>
          
            <li>
    <li class="toctree-l1 ">
        <a class="" href="Models/">Included scatterers</a>
        
    </li>
<li>
          
        </ul>
      </div>
      &nbsp;
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">

      
      <nav class="wy-nav-top" role="navigation" aria-label="top navigation">
        <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
        <a href=".">SDWBA.jl</a>
      </nav>

      
      <div class="wy-nav-content">
        <div class="rst-content">
          <div role="navigation" aria-label="breadcrumbs navigation">
  <ul class="wy-breadcrumbs">
    <li><a href=".">Docs</a> &raquo;</li>
    
      
    
    <li>Introduction</li>
    <li class="wy-breadcrumbs-aside">
      
        
          <a href="https://github.com/ElOceanografo/SDWBA.jl" class="icon icon-github"> Edit on GitHub</a>
        
      
    </li>
  </ul>
  <hr/>
</div>
          <div role="main">
            <div class="section">
              
                <h1 id="sdwba">SDWBA</h1>
<p>This Julia package implements the (stochastic) distorted-wave Born approximation for simple, fluid-like scatterers. The goal is to provide a set of easy-to-use tools to calculate the acoustic backscattering cross-sections of marine organisms using the (stochastic) distorted-wave Born approximation (the DWBA or SWDBA). These models discretize zooplankton or other scatterers as a series of cylindrical sections, and are efficient and accurate for fluid-like organisms, including krill and copepods.</p>
<h2 id="installation">Installation</h2>
<p>To install, run</p>
<pre><code class="julia">Pkg.add(&quot;SDWBA&quot;)
</code></pre>

<p>It can then be loaded the normal way:</p>
<pre><code class="julia">using SDWBA
</code></pre>

<h2 id="basic-use">Basic use</h2>
<h3 id="constructing-scatterers">Constructing Scatterers</h3>
<p>Sound-scattering things (e.g. zooplankton) are represented as <code>Scatterer</code> objects.  A <code>Scatterer</code> contains information about the shape and material properties of such an object.  The (S)DWBA assumes the a deformed cylindrical shape: circular in cross-section, with a varying radius and a centerline that doesn't need to be straight.  A <code>Scatterer</code> represents this shape as a series of discrete segments.</p>
<p>To construct a scatterer, we need to specify the 3-D coordinates of its centerline.  The standard orientation is for the animal's body to lie roughly parallel to the x-axis, with the z-axis pointing up.</p>
<pre><code class="julia">x = linspace(0, 0.2, 10)
y = zeros(x)
z = zeros(x)
</code></pre>

<p>These coordinates are stacked into a 3xN matrix, which will be called <code>r</code>.</p>
<pre><code class="julia">r = [x'; y'; z']
</code></pre>

<p>The scatterer's radius can vary as well.  We'll make ours kinda lumpy.</p>
<pre><code class="julia">a = randn(10).^2  # squared to make sure the're all positive
</code></pre>

<p>We also define the density and sound-speed contrasts <em>h</em> and <em>g</em> (value inside scatterer / value in the surrounding medium).  These can vary from one segmen to another, but will often be assumed constant inside the scatterer.</p>
<pre><code class="julia">h = 1.02 * ones(a)
g = 1.04 * ones(a)
</code></pre>

<p>We can now define the scatterer.</p>
<pre><code class="Julia">weird_zoop = Scatterer(r, a, h, g)
</code></pre>

<h3 id="loading-scatterers-from-file">Loading Scatterers from file</h3>
<p>A function <code>from_csv()</code> is provided to load a scatterer directly from a comma-separated datafile.  This file should have columns for the x, y, z, a, g, and h values of the scatterer.  If the columns have those names, the function will work automatically:</p>
<pre><code class="julia">my_scat = from_csv(&quot;path/to/my_scat.csv&quot;)
</code></pre>

<p>If the columns have some other names, you can provide a dictionary telling the function which is which.</p>
<pre><code class="julia">colnames = Dict([(&quot;x&quot;,&quot;foo&quot;),(&quot;y&quot;,&quot;bar&quot;),(&quot;z&quot;,&quot;baz&quot;), (&quot;a&quot;,&quot;qux&quot;),
    (&quot;h&quot;,&quot;plugh&quot;), (&quot;g&quot;,&quot;garply&quot;)])
my_scat = from_csv(&quot;path/to/my_scat.csv&quot;, colnames)

</code></pre>

<h3 id="build-in-models">Build-in models</h3>
<p>The package comes with a sub-module called <code>Models</code> containing several ready-made <code>Scatterer</code>s.  See the documentation for references for each one.</p>
<pre><code class="julia">krill = Models.krill_mcgeehee
</code></pre>

<h3 id="calculating-backscatter">Calculating backscatter</h3>
<p>There are three functions that calculate backscatter: <code>form_function</code>, <code>backscatter_xsection</code>, and <code>target_strength</code>.  Each is just a wrapper around the one before it, and they all have the same arguments.</p>
<pre><code class="julia">krill = Models.krill_mcgeehee
freq = 120e3 # Hz
sound_speed = 1470 # m/s

# deterministic DWBA
target_strength(krill, freq, sound_speed)

# stochastic SDWBA
phase_sd = 0.7071
target_strength(krill, freq, sound_speed, phase_sd)
</code></pre>

<p>When a frequency and sound speed are provided, the sound is assumed to come from above, as is the usual case with a ship-mounted echosounder.  If you would like it to come from some other direction, you can specify a 3-D wavenumber vector--that is, a vector, pointing in the direction of propagation, whose magnitude is $k = 2 pi f / c$.</p>
<pre><code class="julia">k_mag = 2pi * freq / sound_speed
k_vertical = [0.0, 0.0, -k_mag]
target_strength(krill, k_vertical)

angle = deg2rad(30)
k_slanted = k_mag * [sin(angle), 0, cos(angle)]
target_strength(krill, k_slanted)
</code></pre>

<p>It is usually easier to think of the scatterer tilting than the wavenumber vector.  The <code>rotate</code> function does this easily, accepting roll, tilt, and yaw angles (in degrees) as keyword arguments.</p>
<pre><code class="julia">target_strength(rotate(krill, tilt=30), freq, sound_speed)
target_strength(rotate(krill, tilt=45, roll=10), freq, sound_speed)
</code></pre>

<h4 id="frequency-and-tilt-angle-spectrums">Frequency and tilt-angle spectrums</h4>
<p>Often, we are interested in calculating the target strength of a scatter over a range of frequencies or angles.  Two convenience functions are provided to do this: <code>freq_spectrum</code> and <code>tilt_spectrum</code>.  Both return a dictionary, with results in both the linear and log domains.</p>
<pre><code class="julia">start, stop = 10e3, 1000e3 # endpoints of the spectrum, in Hz
nfreqs = 200
fs = freq_spectrum(krill, start, stop, sound_speed, nfreqs)

require(:PyPlot)
semilogx(fs[&quot;freqs&quot;], fs[&quot;TS&quot;])


ts = tilt_spectrum(krill, -180, 180, k_vertical, 360)

</code></pre>
              
            </div>
          </div>
          <footer>
  
    <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
      
        <a href="API/" class="btn btn-neutral float-right" title="Function Reference"/>Next <span class="icon icon-circle-arrow-right"></span></a>
      
      
    </div>
  

  <hr/>

  <div role="contentinfo">
    <!-- Copyright etc -->
    
  </div>

  Built with <a href="http://www.mkdocs.org">MkDocs</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
	  
        </div>
      </div>

    </section>

  </div>

<div class="rst-versions" role="note" style="cursor: pointer">
    <span class="rst-current-version" data-toggle="rst-current-version">
      
          <a class="icon icon-github" style="float: left; color: #fcfcfc"> GitHub</a>
      
      
      
        <span style="margin-left: 15px"><a href="API/" style="color: #fcfcfc">Next &raquo;</a></span>
      
    </span>
</div>

</body>
</html>

<!--
MkDocs version : 0.14.0
Build Date UTC : 2016-04-06 15:00:16.926750
-->
